Skip to main content

MetaMask API

Detecting that MetaMask is installed and adding additional networks and custom tokens easily make a great dApp user experience, specially those who are not technically skilled. It is important to streamline the onboarding process as much as you can to make it easier for consumers to operate your application. This guide explains how to build a simple button for your front-end application that will automatically add Gnosis to MetaMask.

Summary of actions​

  1. Detect MetaMask or propose its installation
  2. Detect ChainId, and propose to add Gnosis if needed
  3. Detect Account, and propose to connect if needed

Detect MetaMask​

if (typeof window.ethereum !== 'undefined') {
  console.log('MetaMask is installed!');
  //TODO: propose users to install MetaMask
}

Detect Gnosis​

The following code includes all the parameters needed by MetaMask to add Gnosis to its networks programmatically

var GNOSIS_MAINNET_PARAMS = {
    chainId: "0x64",
    chainName: "Gnosis",
    nativeCurrency: {
        name: "xDai",
        symbol: "XDAI",
        decimals: 18,
    },
    rpcUrls: ["https://rpc.gnosischain.com/"],
    blockExplorerUrls: ["https://gnosisscan.io/"],
}

var addGnosisToMetaMask = function() {
    window.ethereum.request({
        method: "wallet_addEthereumChain",
        params: [GNOSIS_MAINNET_PARAMS],
    })
    .catch((error) => {
        console.log(error);
    });
};

Detect account​

Our dApps need access to the user's account, follow this code example to get it:

var getAccount = async function(){
    const accounts = await window.ethereum.request({ method: 'eth_requestAccounts' });
    // MetaMask provide a single account
    console.log(accounts[0]);
    alert(accounts[0]);
}

Add Custom Token to MetaMask​

In addition to directing the user to manually import tokens using the MetaMask UI, you can add code to your dApp's front end to prompt the user to add it to their MetaMask wallet automatically. This can be done using the wallet_watchAsset method. To do so, add the following code to your dApp's front end:

const tokenAddress = 'custom-token-address-on-gnosis';
const tokenSymbol = 'your-token-symbol';
const tokenDecimals = 18; //or how ever many decimals
const tokenImage = 'your-token-image-url';

try {
  // wasAdded is a boolean. Like any RPC method, an error may be thrown.
  const wasAdded = window.ethereum.request({
    method: 'wallet_watchAsset',
    params: {
      type: 'ERC20', // Initially only supports ERC20, but eventually more!
      options: {
        address: tokenAddress, // The address that the token is at.
        symbol: tokenSymbol, // A ticker symbol or shorthand, up to 5 chars.
        decimals: tokenDecimals, // The number of decimals in the token
        image: tokenImage, // A string url of the token logo
      },
    },
  });

  if (wasAdded) {
    console.log('Token Added');
  } else {
    console.log('Failed to add');
  }
} catch (error) {
  console.log(error);
}

Live example​

This documentation site is built in ReactJS, check this sample page to see the above code in action.

More info​